feat(objectql): the two transaction-seam refusals publish their error code as a constant - #16326

Part of #16159

Batch ii of that card's sweep, per the batching ruling recorded on it: the last two mechanical rows of its table, in one file. TransactionUnsupportedError and CrossDatasourceTransactionWriteError each publish their ADR-0112 code as an importable constant, matching the shape set by #16283 and #16259.

Authored by the domain:engine execution seat in session session_01ARYe3yQTQCUFm5qPYNgKaJ, branch claude/issue-16159-transaction-error-code-constants.

⛔ Deliberately NOT in this PR, and untouched: packages/objectql/src/validation/record-validator.ts (1 row — held until VALIDATION_FAILED vs VALIDATION_ERROR is ruled; folding an unruled naming question into a mechanical sweep is what the card's slicing exists to prevent) and content/docs/** (#16281 tracks the doc sweep — see the docs census below, which came back non-zero and still owes no edit).

⚠️ This runs in parallel with PR #16308 (batch i), not behind it. The batch-i round measured check:single-claim-paths and found its SINGLE_CLAIM_PATHS list holds exactly one entry, .objectui-sha; the barrel is not a gate-declared single-writer path, so no gate serialises the two. The only coupling is textual, and this PR's barrel edits sit 6+ lines away from #16308's nearest hunk with no reflow of its lines.

Why these two rows

packages/objectql/src/transaction-errors.ts opens by telling its reader that the errors in it "identify themselves by a code field rather than by instanceof, for the reason DriverConnectError already records: the check has to survive crossing a package boundary, where two copies of this module can exist" — and offered nothing to import. The barrel repeats the instruction twice more, once per class: "code is the boundary-crossing identity" and "code crosses package boundaries". The only way to FOLLOW that published instruction was to re-spell the wire string in the consumer's own package, which acquires a check:error-code-provenance stamp site there and is then free to drift from what the engine throws with no compile error to say so.

⭐ Row 2 is the strongest case on the card so far for the affordance being used rather than merely available: CrossDatasourceTransactionWriteError's own message prescribes a remedy — "split the work into per-datasource units and have the caller reconcile them explicitly" — which is code a caller writes around this refusal, and therefore code that has to recognise it first.

⚠️ Unlike batch i, there is no live first-party consumer re-spelling to point at, and the census is worth stating precisely rather than as a zero. Outside packages/objectql and packages/spec, exactly two files in the repo name either code, and neither is a consumer recognising the refusal:

⇒ The argument for these two rows is the published instruction and the realm split, not a shipped consumer cost. That is a weaker case than batch i's and it is stated as such.

Clause ② — graded per row, from a measurement

Batching changed how many PRs the sweep costs, ⛔ not how each row is graded. Instrument: build at head, swap both changed sources back to their base, rebuild, and compare exported NAME SETS across every declaration file files[] publishes (⛔ not bytes alone: tsup renumbers internal aliases and the shared chunk's filename is content-hashed).

Union over all six published declaration files: 386 ⇒ 388 names, ADDED = the two constants, REMOVED = empty.

Each row is separable in that measurement rather than lumped: each constant appears by name in the ADDED set of both realms, and REMOVED is empty everywhere.

⭐ Four of the six published declaration files are byte-identical across the ablation, which is the stronger statement a name set cannot make: it forecloses JSDoc and member-signature movement on core and on the shared chunk too. Both constants are declared directly in index.d.ts, not through the shared chunk — the opposite of batch i, where two of three reached the barrel only via the chunk.

Ablation hygiene, since these numbers depend on it: implementation committed first; each whole-line anchor proved unique in both directions before anything ran (HEAD new=1 old=0 · BASE new=0 old=1, per row); mutation proven on disk (each path's git hash-object equal to the BASE blob, plus the anchored counts flipped to new=0 old=1); each leg rebuilt with the package's own tsup invoked directly, no turbo cache on the path, and the rebuild proven by dist/index.d.ts mtime moving 1788702203060 ⇒ 1788702393524 ⇒ 1788702414656; restore proven byte-exact (git hash-object equal to the HEAD blob for both paths, git diff HEAD empty, git status --porcelain empty ⇒ zero blast radius); and the restored build's six declaration files are byte-identical hashes to the head snapshot, so the base leg was a measurement and not a blind spot.

⚠️ One aborted run is recorded rather than banked: the first attempt exited on its own anchor-uniqueness proof because the counting helper double-printed on a zero count. Nothing was mutated, the tree was verified clean, the helper was fixed and the ablation re-run from the start.

The two inverted gates, measured rather than predicted

Both codes are registered in ERROR_CODE_LEDGER under @objectstack/objectql (packages/spec/src/api/error-code-ledger.zod.ts), like #16283's and #16308's rows and unlike #16259's. The prediction that follows was checked on both sides of the change, not assumed:

• check:error-code-provenance is NOT neutral. 311 ⇒ 313 registered-code stamp sites, 295 ⇒ 297 listed, waivers unchanged at 16, scanned 2176 files both sides, exit 0 both sides. Exactly +1 per row: each new constdef is a stamp site this gate sees, and it passes because the code is listed under this package's own owner key.
• check:dispatcher-error-vocabulary does not move. The two runs' output is byte-identical (diff of the full logs, banner excluded: 0 lines) — 66 unregistered code-stamping sites all classified, 2372 non-test source files, 303 registered codes, exit 0 both. That table records UNREGISTERED sites, so a registered code is invisible to it by construction, and no row in packages/runtime/src/dispatcher-error-vocabulary.ts changes. No cross-package edit is owed for either row.

Shape, and one deliberate deviation from batch i

Follows #16283: export const X_CODE = '…' as const; beside its class, the class field as a bare readonly code = X_CODE; (⛔ no as const on the FIELD — check:dispatcher-error-vocabulary's classconst pattern requires the constant name to be followed by ;, , or a newline, so the suffix would take the site out of it), re-exported from index.ts beside the class. Each string is byte-identical to the literal it replaces: the quoted wire spelling occurs exactly once per code in the file on both sides — it moved, it did not multiply or mutate.

⭐ The deviation: each constant and its docblock sit ABOVE the class's own docblock, not between that docblock and the class. Measured on the real emitter, on this branch, with a firing counterfactual: with the constant interposed (PR #16308's placement), tsup emits declare class TransactionUnsupportedError with zero lines between it and the constant — the class's own documentation is emitted onto the CONSTANT and the class ships undocumented. With the constant above, both keep their own docblock in the published dist/index.d.ts. A standalone tsc --declaration probe gives the same answer and explains it: two consecutive JSDoc blocks both attach to the declaration that follows them. The grouped shape #16259 landed in registry.ts already avoids this. The counterfactual leg was restored byte-exact and the tree rebuilt to a dist byte-identical to the head snapshot.

⚠️ That is a live observation about #16308, which is open and unmerged and whose three classes all carry real docblocks; it is review feedback on that PR rather than a defect on origin/main, so it is reported to the dispatching seat and not filed as a card.

⭐ Neither class in this file is published from the lean ./core entry (control: core.ts names DriverConnectError, and names no Transaction symbol at all), so the batteries-only placement of these constants introduces no asymmetry here and adds nothing to #16260's population — class and constant are reachable from exactly the same entry point. That is a different reading from batch i, where two of the three classes ARE on ./core.

Verification

• Tests — two new pin files, one per row (transaction-unsupported-code-constant.test.ts, cross-datasource-transaction-write-code-constant.test.ts), five cases each: the literal wire string (the byte-identity fence, deliberately NOT a constant compare — a pin that reads the constant cannot catch the constant being wrong), the code a real refusal carries asserted with name and the discriminating payload (⛔ never a bare toThrow()), barrel reachability by identity, barrel-class/barrel-constant agreement, and a cross-realm copy where instanceof is false while the code compare holds. Row 2's case 2 drives all three write operations, pinning that the three messages differ while the three codes are equal. ⚠️ Neither class carries a status field, so ADR-0112's code + status minimum reduces to code plus the discriminating fields; ⛔ inventing a status would be new published surface and is not what this card converts.
• pnpm --filter @objectstack/objectql exec vitest run over those two plus the four existing suites that exercise these refusals — 6 files / 65 tests passed, exit 0.
• pnpm --filter @objectstack/objectql typecheck — exit 0, including check:test-typecheck: the test-layer debt ledger holds at 44 files / 242 errors / 69 pinned signatures, unchanged. Both new test files are proven inside that program by tsc --noEmit --listFiles -p tsconfig.test.json (1 hit each; firing control 1, negative control 0) and contribute 0 of the 242 — the 242 error lines in the same log are the firing control for that grep.
• Gate families — derived from the actual diff by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (5 paths vs merge base 1ca95df16), 61 runnable commands, 57 exit 0, each captured redirect-then-read and ⛔ never through a pipe. The four that did not are NOT MEASURED rather than red, and none is about this diff: check:dual-build-cjs-loads, check:published-readme-exports and check:type-check-debt returned exit 3 PREREQUISITE NOT MET (they read built output), and check:react-declaration-parity printed "MANIFEST is not set — this gate did NOT run" (it needs an objectui build and a browser).
• After a full workspace build (71/71 tasks) all three exit-3 gates are real greens over a population that includes this package: check:dual-build-cjs-loads exit 0 (103 published require entry points across 66 packages, 619 emitted CommonJS files parse); check:published-readme-exports exit 0 (324 documented symbols); check:type-check-debt exit 0 (12 ledger entries re-measured in 162s, 140 raw errors, none above its recorded number).
• ⚠️ check:dts-closure's first green was about a population that mostly excluded this tree — exit 0 while sweeping 15 built packages, because only objectql's dependency closure had been built. Re-run after the workspace build: 71 built packages, 163/163 declared declaration files present, exit 0. Quoting the first reading as evidence would have been the vacuous-green shape.
• Repo-wide pnpm lint (eslint . --no-inline-config) run IN FULL, exit 0 — ⛔ no narrowing claimed. Non-vacuity control: re-running eslint over exactly the four changed/added TypeScript files with --format json reports 4 files linted, 0 errors, 0 warnings, and the changeset .md is in eslint's population too (1 file linted), so the repo-wide green demonstrably covers all five changed files.
• Docs census — the zero is not where it was expected. TransactionUnsupportedError, CrossDatasourceTransactionWriteError and both new constant names appear in 0 files under content/docs, but both wire codes appear in 2 files each: references/api/contract.mdx and references/api/error-code-ledger.mdx, which are AUTO-GENERATED enumerations of the ledger vocabulary. No edit is owed — this diff registers no new code and touches no file under packages/spec, so the enumerated vocabulary is unchanged. Firing controls on the same corpus: @objectstack/objectql 12 files, ERR_READONLY_FIELD_REJECTED 3, transaction 42; negative control 0. ⛔ content/docs/releases/** is untouched.

Every reading above was taken at this branch's head.

Generated by Claude Code